Simplify by avoiding the / character and being more descriptive. Unclear if each "parallel branch" must have the same action/subgraph.

Rephrased:

Burr can run multiple actions in parallel. Each parallel branch can contain one or more actions, and different branches can have different actions. This is useful when:
(simple use case)

• Trying different prompts with an LLM
• Trying a prompt with different LLMs
• Trying multiple prompts with multiple LLMs
• Do semantic search and web search simultaneously for information retrieval
• and more! Just like Burr in general, these concepts are generic and can be applied to non-LLM applications

This section shows how to enable parallelism and presents use cases.

It's important to paint a picture about "what can it do" in the first sentence because reading the TL;DR wasn't super helpful for me, then we jump into the API and I still can't picture it.

Currently, this top-level intro, the TL;DR and the Overview section are a bit redundant

Nice, thanks

I don't think that's the right header hierarchy. I'd remove the General Idea/TL;DR and promote everything underneath it

Being the first header, this is difficult to decrypt. It's unclear if "parallel action" is a Burr construct. If yes, then simply name the Python objects. Even though there's a navigation menu, I'd use this section to give details on all the different approaches.

Rephrased based on the keypoints I identified:

Burr provides a high-level and a low-level API for parallelism. The high-level API supports many different patterns and should be sufficient for most use cases.
High-Level

• MapStates: Apply an action to multiple values in state then reduce the action results (e.g., different prompts to the same LLM).
• MapActions: Apply different actions to the same state value then reduce the actions result (e.g., same prompt to different LLMs).
• MapActionsAndStates: Do the full cartesian product of actions and state values (e.g., try different prompts with multiple LLMs)
• RunnableGraph: Combined with the above options, you can replace a single Action by a Graph composed of multiple actions.

With the low-level API, you can manually determine how parallel actions or subgraphs are executed.

Instead of the abstract concepts, refer to the example's content.

• We define a regular action query_llm_action() using the @action decorator. We also create a subclass of MapStates named TestMultiplePrompts, which must implement .reads(), .writes(), .action(), .states(), and .reduce().
• .reads() / .writes() define the state value it can interact with, just like the @action decorator
• .action() leverages the query_llm_action() previously defined
• .states() can read value from State and yields values to pass to the . action(). In this case, it updates the prompt state value that's read by query_llm_action(). (the example hardcoded a list of prompts for simplicity, but this would be read from state)
• .reduce() receives multiple states, one per .action() call, where the llm_output value is set by query_llm_action() in .action(). Then, it must set all_llm_output as specified in the MapStates.writes() method.

I understand why the hardcode values are present in the example, but it made me scratch my head for a second. The above reference should be pretty easy to copy-paste for the subsequent sections

Briefly name the Python constructs involved and how they differ from the "high-level" API

Idea

All of the aforementioned high-level API are implemented as subclasses of TaskBasedParallelAction. You can subclass it directly and implement the .tasks() method that yields SubGraphTask, which can be actions or subgraphs. These tasks are then executed by the burr.Executor implementations

Should this be named query_llm_action? The first example and the text above use that name.

Hmm, good point re: consistency! I think it's better if everything else is called query_llm -- this is the only one with action appended, and the docs switch between. Changed!

The examples here use the same action with different parameters bound to it. Is it possible to instead map over different actions completely? For example something like this:

@action(reads["query"], writes=["llm_output"])
def query_llm(state: State) -> State:
    return state.update(llm_output=some_function(state["query"]))

@action(reads["query"], writes=["llm_output"])
def count_tokens(state: State) -> State:
    return state.update(llm_output=another_function(state["query"]))

@action(reads["query"], writes=["llm_output"])
def draw_chart(state: State) -> State:
    return state.update(llm_output=a_third_function(state["query"]))

def actions(self, state: State) -> Generator[Action | Callable | RunnableGraph, None, None]:
    for action in [
        query_llm,
        count_tokens,
        draw_chart,
    ]:
        yield action

As a follow up question, is there a requirement that all the actions have to write the same keys? My naive intuition is that this is not a requirement, but I would have to do some extra work in the reduce function to make sure I get all available outputs:

@action(reads["query"], writes=["llm_output"])
def query_llm(state: State) -> State:
    ..
@action(reads["query"], writes=["token_count"])
def count_tokens(state: State) -> State:
    ..
@action(reads["query"], writes=["chart_bytes"])
def draw_chart(state: State) -> State:
    ..

def reduce(self, states: Generator[State, None, None]) -> State:
    outputs = {}
    for state in states:
        if "llm_output" in state:
            outputs["llm_output"] = state["llm_output"]
        if "token_count" in state:
            outputs["token_count"] = state["token_count"]
        if "chart_bytes" in state:
            outputs["chart_bytes"] = state["chart_bytes"]
        return state.update(outputs)

def writes() -> List[str]:
    return ["llm_output", "token_count", "chart_bytes"]

Alternatively, perhaps it would be better to do this to avoid burr complaining that a particular state key was not present in the output

def reduce(self, ..):
    outputs = {}
    ..
    return state.update({"outputs": outputs})

def writes():
    return ["outputs"]

Sorry for the long comment, just trying to wrap my head around the possibilities with the new API!

Hey! Yes, I think that's supported (If I understand correctly). It's a little nuanced (and I could explain it better), but the idea is that the generator can yield an Action object, a Callable (function that will get turned into an action, or a RunnableGraph (a subgraph that functions as an action). Specifically, this allows you to do exactly what you want/mix + match.

The way to reconcile this with the example (with multiple .bind()) calls is that the .bind creates a new action, so for the sake of the actions generator it doesn't really matter whether it was created through .bind(...) or created through specifying another action entirely!

Regarding the follow-up, currently, yes, it's necessary to apply defaults. This is not a feature of parallelism, rather a feature of Burr. Specifically, we want some strict sense of what an action writes so we have guarentees on what should show up next. The general approach is to apply defaults -- E.G. say if state doesn't contain foo, it'll be None -- I think the simplest in your case would be to do something like:

def reduce(self, states: Generator[State, None, None]) -> State:
    outputs = {'llm_output' : None, 'token_count' : None, 'chart_bytes' : None}  # initialize so you can overwrite with results
    # This is generic, or just have it like you did above, easier to read maybe
    for state in states:
        for key in list(outputs):
            if key in state:
                output[key] = state[key]
        return state.update(outputs)

Amazing, thank you! This new API is going to be very helpful for us :)

Great! Would love to hear about how you'd be using it/specifics (only if you feel comfortable sharing). This can help us get a sense of ergonomics (and we can send you test versions if you're interested in messing with it). Feel free to join the discord and DM us if that would be useful!

nit: I think there's a colon : missing from the for and an extra colon at the end of the def state(..) :)

Thanks! Good find. Will update 🙏

this section should be updated to reflect what we've shipped though?